<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Semantic Actions with Generators</title>
<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Spirit 2.5.8">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="generate_api/create_generator.html" title="API for Automatic Generator Creation">
<link rel="next" href="auto.html" title="Auto Generator">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="generate_api/create_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auto.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="spirit.karma.reference.action"></a><a class="link" href="action.html" title="Semantic Actions with Generators">Semantic Actions with
        Generators</a>
</h4></div></div></div>
<h6>
<a name="spirit.karma.reference.action.h0"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.description"></a></span><a class="link" href="action.html#spirit.karma.reference.action.description">Description</a>
        </h6>
<p>
          Semantic actions may be attached to any point in the grammar specification.
          They allow to call a function or function object in order to provide the
          value output by the generator attached to the semantic action. Semantic
          actions are associated with a generator using the syntax <code class="computeroutput"><span class="identifier">g</span><span class="special">[]</span></code>,
          where <code class="computeroutput"><span class="identifier">g</span></code> is an arbitrary
          generator expression.
        </p>
<h6>
<a name="spirit.karma.reference.action.h1"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.header"></a></span><a class="link" href="action.html#spirit.karma.reference.action.header">Header</a>
        </h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/karma/action.hpp&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_action</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<p>
          Also, see <a class="link" href="../../structure/include.html" title="Include">Include Structure</a>.
        </p>
<h6>
<a name="spirit.karma.reference.action.h2"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.model_of"></a></span><a class="link" href="action.html#spirit.karma.reference.action.model_of">Model
          of</a>
        </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
            <a class="link" href="generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>
          </p></blockquote></div>
<div class="variablelist">
<p class="title"><b>Notation</b></p>
<dl class="variablelist">
<dt><span class="term"><code class="computeroutput"><span class="identifier">a</span></code>, <code class="computeroutput"><span class="identifier">g</span></code></span></dt>
<dd><p>
                Instances of a generator, <code class="computeroutput"><span class="identifier">G</span></code>
              </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">A</span></code></span></dt>
<dd><p>
                Attribute type exposed by a generator, <code class="computeroutput"><span class="identifier">a</span></code>
              </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">fa</span></code></span></dt>
<dd><p>
                A (semantic action) function with signature <code class="computeroutput"><span class="keyword">void</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&amp;,</span> <span class="identifier">Context</span><span class="special">&amp;,</span> <span class="keyword">bool</span><span class="special">&amp;)</span></code>. The third parameter is a boolean
                flag that can be set to false to force the generator to fail. Both
                <code class="computeroutput"><span class="identifier">Context</span></code> and the boolean
                flag are optional. For more information see below.
              </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">Attrib</span></code></span></dt>
<dd><p>
                The attribute to be used to generate output from.
              </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">Context</span></code></span></dt>
<dd><p>
                The type of the generator execution context. For more information
                see below.
              </p></dd>
</dl>
</div>
<h6>
<a name="spirit.karma.reference.action.h3"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.expression_semantics"></a></span><a class="link" href="action.html#spirit.karma.reference.action.expression_semantics">Expression
          Semantics</a>
        </h6>
<p>
          Semantics of an expression is defined only where it differs from, or is
          not defined in <a class="link" href="generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>.
        </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Expression
                  </p>
                </th>
<th>
                  <p>
                    Semantics
                  </p>
                </th>
</tr></thead>
<tbody><tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">g</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Call semantic action, <code class="computeroutput"><span class="identifier">fa</span></code>
                    <span class="emphasis"><em>before</em></span> invoking <code class="computeroutput"><span class="identifier">g</span></code>.
                    The function or function object <code class="computeroutput"><span class="identifier">fa</span></code>
                    is expected to provide the value to generate output from to the
                    generator <code class="computeroutput"><span class="identifier">g</span></code>.
                  </p>
                </td>
</tr></tbody>
</table></div>
<p>
          The possible signatures for functions to be used as semantic actions are:
        </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&amp;</span> <span class="identifier">attr</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Context</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&amp;</span> <span class="identifier">attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">&amp;</span> <span class="identifier">context</span><span class="special">);</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Context</span><span class="special">&gt;</span>
<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&amp;</span> <span class="identifier">attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">&amp;</span> <span class="identifier">context</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&amp;</span> <span class="identifier">pass</span><span class="special">);</span>
</pre>
<p>
          The function or function object is expected to return the value to generate
          output from by assigning it to the first parameter, <code class="computeroutput"><span class="identifier">attr</span></code>.
          Here <code class="computeroutput"><span class="identifier">Attrib</span></code> is the attribute
          type of the generator attached to the semantic action.
        </p>
<p>
          The type <code class="computeroutput"><span class="identifier">Context</span></code> is the
          type of the generator execution context. This type is unspecified and depends
          on the context the generator is invoked in. The value <code class="computeroutput"><span class="identifier">context</span></code>
          is used by semantic actions written using <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a>
          to access various context dependent attributes and values. For more information
          about <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a>
          placeholder expressions usable in semantic actions see <a class="link" href="generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a>.
        </p>
<p>
          The third parameter, <code class="computeroutput"><span class="identifier">pass</span></code>,
          can be used by the semantic action to force the associated generator to
          fail. If pass is set to <code class="computeroutput"><span class="keyword">false</span></code>
          the action generator will immediately return <code class="computeroutput"><span class="keyword">false</span></code>
          as well, while not invoking <code class="computeroutput"><span class="identifier">g</span></code>
          and not generating any output.
        </p>
<h6>
<a name="spirit.karma.reference.action.h4"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.attributes"></a></span><a class="link" href="action.html#spirit.karma.reference.action.attributes">Attributes</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Expression
                  </p>
                </th>
<th>
                  <p>
                    Attribute
                  </p>
                </th>
</tr></thead>
<tbody><tr>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">a</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]</span></code>
                  </p>
                </td>
<td>
                  <p>
                    <code class="computeroutput"><span class="identifier">a</span><span class="special">:</span>
                    <span class="identifier">A</span> <span class="special">--&gt;</span>
                    <span class="identifier">a</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]:</span>
                    <span class="identifier">A</span></code>
                  </p>
                </td>
</tr></tbody>
</table></div>
<h6>
<a name="spirit.karma.reference.action.h5"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.complexity"></a></span><a class="link" href="action.html#spirit.karma.reference.action.complexity">Complexity</a>
        </h6>
<p>
          The complexity of the action generator is defined by the complexity of
          the generator the semantic action is attached to and the complexity of
          the function or function object used as the semantic action.
        </p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
            Please note that the use of semantic actions in <span class="emphasis"><em>Spirit.Karma</em></span>
            generally forces the library to create a <span class="emphasis"><em>copy</em></span> of
            the attribute, which might be a costly operation. Always consider using
            other means of associating a value with a particular generator first.
          </p></td></tr>
</table></div>
<h6>
<a name="spirit.karma.reference.action.h6"></a>
          <span class="phrase"><a name="spirit.karma.reference.action.example"></a></span><a class="link" href="action.html#spirit.karma.reference.action.example">Example</a>
        </h6>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            The test harness for the example(s) below is presented in the <a class="link" href="basics.html#spirit.karma.reference.basics.examples">Basics
            Examples</a> section.
          </p></td></tr>
</table></div>
<p>
          Some includes:
        </p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
</pre>
<p>
        </p>
<p>
          Some using declarations:
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">int_</span><span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">val</span><span class="special">;</span>
</pre>
<p>
        </p>
<p>
          Some examples:
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">42</span><span class="special">;</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"42"</span><span class="special">,</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">_1</span> <span class="special">=</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">i</span><span class="special">)]);</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"abc"</span><span class="special">,</span> <span class="identifier">string</span><span class="special">[</span><span class="identifier">_1</span> <span class="special">=</span> <span class="identifier">val</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)]);</span>
</pre>
<p>
        </p>
<p>
          More examples for semantic actions can be found here: <a class="link" href="../tutorials/semantic_actions.html#spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions">Examples
          of Semantic Actions</a>.
        </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="generate_api/create_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auto.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
